TRANSACTIONS PLUGIN
--------------------
Authors: Mike Barlow


INTRODUCTION
-------------

A transactions plugin used to easily take payments and keep a record of all the transactions (and the transaction items) taken place.


FEATURES
---------

Take payments from clients
Transactions list for front end / my account section and tab for transactions by user in the admin
Simple to setup new gateways
Refund option
- Doesn't interface with gateways, only for local tracking. User would have to refund via (for example) sagepay admin, then login and refund the transaction on their site.


REQUIREMENTS
-------------

You will need to make sure you have the latest version of core which has the admin users add / edit functionality running through our scaffolding system.



CURRENT GATEWAYS SUPPORTED
---------------------------

Sagepay Server
Stripe
PayPal
Manual Payment


INSTALLATION
-------------

1) This is a composer plugin so from www/app just run composer as:-

	composer require evoluted/transactions

   Depending on the payment gateway you're using, you may need to install additional plugins.

   EvTransactions features components to handle various payment gateways, but these are being moved out in to their own plugins.

   You may therefore need to install one of the following:
   - SagePay (composer require evoluted/sagepay)
   - PayPal (composer require evoluted/paypal)
   - Stripe (composer require evoluted/stripe)

   These plugins may be set up to install third-party payment gateway code alongside them.

   Various gateways still have their implementations built in to EvTransactions. Some of these may require you to install their corresponding Omnipay gateway.

   For example, if using Worldpay, you will need to run the command:-

    composer require omnipay/worldpay

   Check the head of the corresponding component within EvTranasaction to see what you will need to include.

2) Add the following code to the app/Config/bootstrap.php plugin load array.

'Transactions'=>array(
	'routes' => true,
	'bootstrap' => true
)

3) To setup the database use the CakeDC Migrations plugin. To run the migrations and setup the database run:-

	Console/cake Migrations.migration run all --plugin EvTransactions

   You may need to setup some additional tables depending on the payment gateway you intend to use. The SQL scripts for these are found in the plugin's _assets folder. For example Sagepay Server requires an extra table.


4) On the User model, place the following relationship.

	public $hasMany = array(
		'Transaction' => array(
			'className' => 'EvTransactions.Transaction',
			'foreignKey' => 'model_id',
			'conditions' => array(
				'model' => 'User'
			)
		)
	);

4a) If you wish to link a transaction to specific models, e.g. you may want to link the transaction to an order. Copy the following relationship to each of those models, switching out the correct model name.

	public $hasOne = array(
		'Transaction' => array(
			'className' => 'EvTransactions.Transaction',
			'foreignKey' => 'model_id',
			'conditions' => array(
				'Transaction.model' => 'MODELNAME'
			)
		)
	);

4b) If you wish to link a transaction item to a specific model, e.g. could link each transaction item to each order item row. Copy the following relationship to each of those models, switching out the correct model name.

	public $hasOne = array(
		'TransactionItem' => array(
			'className' => 'EvTransactions.TransactionsItem',
			'foreignKey' => 'model_id',
			'conditions' => array(
				'TransactionsItem.model' => 'MODELNAME'
			)
		)
	);

4c) If you are going to be making use of the "My Transactions" listing page or the "Transactions" tab on the user edit screen in the admin, make sure you setup the Transaction to Model relationship in the config file
as described in step 6.


5) Any controller where a transaction will be taking place, add the following component:

	public $components = array(
		'EvTransactions.Transactions'
	);

6) The plugin has been setup using the standard bootstrap file and code found on the dev wiki. Meaning you can override some config options by placing a config file in the following location: app/Config/Plugin/transactions.php
Available options are:

'gateway' - The gateway to use, this is a snake cased version of the component name minus the word 'component'. I.E. SagepayServerComponent -> sagepay_server
		  - The value of this is also used as the 'key' value for element in the config containing settings for that gateway.

'currency' - The currency to use, this could vary depending on the gateway, default value is 'gbp'

'transaction_relation' - This is an array containing all the possible 'hasOne' relationships the transaction could have. This is used to connect the polymorphic model / model_id values on the transaction
					   - to the order or booking table. Used so we can get the related data on the transaction listing page.
					   - With it being polymorphic, multiple 'hasOne' relationships can be setup here if you are taking payments for multiple things on one site, such as membership renewals and bookings
					   - for events.

'transactions_item_relation' - This is an array containing all the possible 'hasOne' relationships the transaction item could have. This is used to connect the polymorphic model / model_id values on the
							 - transaction item to the order items or booking item table. Used so we can get the related data on the transaction listing page.
						   	 - With it being polymorphic, multiple 'hasOne' relationships can be setup here if you are taking payments for multiple things on one site, such as membership renewals and bookings
						   	 - for events.

'listing' - This is an array containing the details needed to generate the transaction listing page on front end or in the user edit tab.
	- 'contain' - array of Models to contain and bring in on the listing. Models will be contained from the Transaction Model, so choose models you have specified in the 'transaction_relation' array.
	- 'page_id' - Page id to bring in page title / intro text on the front end "My Transactions" page.
	- 'display_field' - A 'Model' => 'fieldname' type array, used to get a name for each of the transaction rows. So you could display the product name or event name if you are taking bookings.
					  - If no options are specified for this, it will attempt to fallback on description fields from the TransactionsItem model to generate the display field.


Other options in the config file should be the settings for each gateway as mentioned in the 'gateway' option details.
For template configuration arrays for each gateway check the _assets/gateway_configs folder.
In most cases there should be a dev / live sub array for each gateway, the gateway component itself should handle the switching of dev / live based of settings from the main app bootstrap file.

An example config file can be found in Transactions/Config/config_example.php

7) Once gateway information is setup you should be ready to take payments!


FUTURE
-------

More components coded for different gateways.

